home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / developer-tools / guis / gadutil / docs / autodocs / 01.gu_layoutgadgetsa < prev    next >
Encoding:
Text File  |  1996-07-16  |  33.3 KB  |  813 lines
  1. gadutil.library/GU_LayoutGadgetsA           gadutil.library/GU_LayoutGadgetsA
  2.  
  3.    NAME
  4.     GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
  5.  
  6.    SYNOPSIS
  7.     gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  8.     D0,A0                        A0        A1       A2      A3
  9.  
  10.     APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  11.         struct Screen *, struct TagItem *);
  12.  
  13.    FUNCTION
  14.     Creates a laid-out gadget list from a LayoutGadget array, which
  15.     describes each gadget you want to create. Gadgets you create can
  16.     be any of the gadget kinds supported by GadTools, as well as any
  17.     of the extended gadget kinds provided by GadUtil.
  18.     The gadgets created by this routine, can easily be defined so that
  19.     they adjust their sizes and positions to accomodate fonts of any
  20.     size, and also adapt to different locale strings.
  21.     
  22.    INPUTS
  23.     gad_list - a pointer to the gadget list pointer. This will be
  24.            ready to pass to OpenWindowTagList() or AddGList().
  25.  
  26.     gadgets - an array of LayoutGadget structures. Each element in
  27.           the array describes one of the gadgets that you will
  28.           be creating. Each LayoutGadget structure in the array
  29.           should be initialized as follows:
  30.  
  31.           lg_GadgetID - the ID for this gadget. An ID of -1
  32.                 terminates the array. Don't use gadget ID's
  33.                 in the range 65000(-536) to 65535 (-1). These
  34.                 may be used internally in later versions of
  35.                 GadUtil.
  36.  
  37.           lg_LayoutTags - tags that describes each gadget to
  38.                   create. These tags is used to calculate
  39.                   positions, sizes and other attributes
  40.                   of the created gadgets.
  41.  
  42.           lg_GadToolsTags - additional tags for GadTools gadgets.
  43.                     This would be the same set of tags that
  44.                     you might pass to CreateGadgetA() if
  45.                     you were using GadTools directly.
  46.  
  47.           lg_Gadget - the pointer to the Gadget structure created
  48.                   for this gadget will be placed here. You
  49.                   should initialize this field to NULL. The
  50.                   gadget structure created should be considered
  51.                   READ ONLY! This field will contain a pointer
  52.                   to a struct BBoxData, if the created gadget
  53.                   kind is a BEVELBOX_KIND or a LABEL_KIND.
  54.  
  55.           Assembly language programmers can use the macro GADGET:
  56.  
  57.             GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
  58.  
  59.     screen - a pointer to the screen that the gadgets will be created
  60.          for. This is required, so that the layuot routines can
  61.          get display info about the screen where the rendering
  62.          will be done. Use LockPubScreen() to use a public screen,
  63.          or OpenScreenTagList(), if you want to use your own screen.
  64.  
  65.     taglist - pointer to an array of tags providing optional extra
  66.           parameters, or NULL.
  67.  
  68.                   These tags can be used here:
  69.  
  70.                     GU_RightExtreme (ULONG *)
  71.                       A pointer to a longword that is used to store the
  72.                       rightmost point that a gadget will exist in.
  73.  
  74.                     GU_LowerExtreme (ULONG *)
  75.                       A pointer to a longword that is used to store the
  76.                       lowermost point that a gadget woll exist in.
  77.  
  78.                     GU_Catalog (struct Catalog *)
  79.                       A pointer to the programs translation catalog. NULL
  80.                       indicates that the program should use the internal
  81.                       strings. You must open the catalog by yourself (use
  82.                       GU_OpenCatalog() or locale/OpenCatalog). The
  83.                       GU_AppStrings tag MUST be used together with this tag.
  84.  
  85.                     GU_DefTextAttr (struct TextAttr *)
  86.                       Specifies the default font to use with all gadgets. Can
  87.                       be overridden with GU_TextAttr tag for each gadget.
  88.  
  89.                     GU_AppStrings (struct AppString *)
  90.                       A pointer to an array of AppString structures. These
  91.                       strutures contains the programs internal strings. This
  92.                       tag must be used together with the GU_Catalog tag.
  93.  
  94.                     GU_BorderLeft (ULONG)
  95.                       Size of the window's left border.
  96.  
  97.                     GU_BorderTop (ULONG)
  98.                       Size of the window's top border.
  99.  
  100.                     GU_NoCreate (BOOL)
  101.                       Don't create any gadgets. Useful to determine if the
  102.                       window will fit on the screen etc.
  103.  
  104.                     GU_MinimumIDCMP (ULONG *)
  105.                       A pointer to a longword that is used to store the
  106.                       minimum required IDCMP flags, so that all gadgets will
  107.                       work. The longword can already be initialized, and any
  108.                       new needed IDCMP flags will be appended to that
  109.                       longword.
  110.  
  111.    TAGS
  112.  
  113.    Tags for the gadgets lg_LayoutTags taglist. The other tags can be found in
  114.    the autodoc to gadtools.library/CreateGadgetA().
  115.  
  116.    GU_GadgetKind (ULONG)
  117.       Can be any of the standard GadTools gadget kinds, or one of the
  118.       extensions provided by GadUtil. Currently extended types are:
  119.  
  120.          IMAGE_KIND
  121.            A gadget that uses an Intuition Image structure for its
  122.            contents. Selected and unselected states can use different
  123.            images. The images are centered automatically.
  124.  
  125.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  126.            a Gadget structure.
  127.  
  128.            Extra tags for IMAGE_KIND:
  129.  
  130.               GUIM_Image (struct Image *)
  131.                  Image for the gadget in its unselected state. This is
  132.                  the only required (extra) tag for IMAGE_KIND gadgets.
  133.  
  134.               GUIM_SelectImg (struct Image *)
  135.                  Image for the gadget in its selected state. If this tag
  136.                  is omitted, the selected image will be the same as the
  137.                  unselected, and only the border and the background color
  138.                  will change (depending on the GUIM_BOOPSILook tag).
  139.  
  140.               GUIM_ReadOnly (BOOL)
  141.                  TRUE to create a read-only image gadget.
  142.  
  143.               GUIM_BOOPSILook (BOOL)
  144.                  This tag will allow the programmer to select how the
  145.                  secondary image should be shown, if only one image is
  146.                  used for the gadget. Defaults to TRUE, which means that
  147.                  the background color will change when the user selects
  148.                  the gadget.
  149.  
  150.          DRAWER_KIND
  151.            A "select drawer" image button. This can be used to select
  152.            a path, but is often used to select files.
  153.  
  154.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  155.            a Gadget structure.
  156.  
  157.          FILE_KIND
  158.            A "select file" image button. This can be used to allow the
  159.            user to select a file. Most programs uses the DRAWER_KIND
  160.            for both file and path selection.
  161.  
  162.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  163.            a Gadget structure.
  164.  
  165.          BEVELBOX_KIND
  166.            A GadTools bevelbox. Use this to avoid the use of absolute
  167.            sizing of bevelboxes. All bevel box kinds from OS3.0 is
  168.            supported, even if the computer only has OS2.0.
  169.  
  170.            The function GU_RefreshBoxes() can be used to redraw all
  171.            bevelboxes.
  172.  
  173.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  174.            a BBoxData structure.
  175.  
  176.            Extra tags for BEVELBOX_KIND:
  177.  
  178.               GUBB_Recessed (BOOL)
  179.                  Create a recessed ("pushed in") bevel box. Differs from
  180.                  the GadTools tag GTBB_Recessed, in that it works with
  181.                  both TRUE and FALSE as parameter. GadTools creates a
  182.                  recessed box independent from the given value.
  183.  
  184.                  Defaults to FALSE.
  185.  
  186.               GUBB_FrameType (ULONG)
  187.                  Determines what kind of box this function renders. The
  188.                  current available alternatives are:
  189.  
  190.                     BFT_BUTTON - Generates a box like what is used around
  191.                                  a GadTools BUTTON_KIND gadget.
  192.  
  193.                     BFT_RIDGE - Generates a box like what is used around
  194.                                 a GadTools STRING_KIND gadget.
  195.  
  196.                     BFT_DROPBOX - Generates a box suitable for a standard
  197.                                   icon drop box imagery.
  198.  
  199.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  200.                                    Can also be used to draw a normal line,
  201.                                    using 1 for the line's height.
  202.  
  203.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  204.                                   also be used to draw a normal line, using
  205.                                   1 for the line's width.
  206.  
  207.                  Defaults to BFT_BUTTON.
  208.  
  209.               GUBB_TextColor (ULONG)
  210.                  Selects which color to print the title text in. Only useful
  211.                  for a bevelbox with a title. Defaults to the color of the
  212.                  TEXTPEN.
  213.  
  214.               GUBB_TextPen (ULONG)
  215.                  Selects which pen to print the title text in. Only
  216.                  useful for a bevelbox with a title. Defaults to TEXTPEN.
  217.                  This tag overrides the GUBB_TextColor tag.
  218.  
  219.               GUBB_Flags (ULONG)
  220.                  Flags for text placement, text shadowing and 3D text:
  221.  
  222.                  Y-pos flags
  223.                  ~~~~~~~~~~~
  224.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  225.                                     border of the box           ___Example___
  226.  
  227.                     BB_TEXT_IN    - Places the bevel box text at the upper
  228.                                     border of the box           ---Example---
  229.  
  230.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  231.                                     border of the box           ___       ___
  232.                                                                    Example
  233.                  X-pos flags
  234.                  ~~~~~~~~~~~
  235.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  236.                                      of the upper border        ---Example---
  237.  
  238.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  239.                                      the left edge of the box   -Example-----
  240.  
  241.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  242.                                      the right edge of the box  -----Example-
  243.  
  244.                  Combined flags
  245.                  ~~~~~~~~~~~~~~
  246.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  247.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  248.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  249.  
  250.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  251.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  252.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  253.  
  254.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  255.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  256.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  257.  
  258.                  Default is BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  259.                  position flags by OR:ing them together. Don't combine two X
  260.                  or two Y flags together.
  261.                 
  262.                  Shadow placement flags
  263.                  ~~~~~~~~~~~~~~~~~~~~~~
  264.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  265.                                    below and to the right of the text. 
  266.  
  267.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  268.                                    above and to the right of the text. 
  269.  
  270.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  271.                                    below and to the left of the text. 
  272.  
  273.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  274.                                    above and to the left of the text. 
  275.  
  276.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  277.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  278.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  279.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  280.  
  281.                  Default is BB_SHADOW_DR (BB_SUNAT_UL).
  282.  
  283.                     BB_3DTEXT    - This flag can be used in place of the tag
  284.                                    GUBB_3DText, TRUE
  285.  
  286.               GUBB_3DText (BOOL)
  287.                  Enables the shadow on the bevel box text. This tag must be
  288.                  used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  289.                  Another way to enable 3D text is to set the flag BB_3DTEXT
  290.                  in the GUBB_Flags tag.
  291.  
  292.               GUBB_ShadowColor (ULONG)
  293.                  Selects which color to print the shadow text in. Only useful
  294.                  for a bevelbox with a title. Defaults to the color of the
  295.                  SHADOWPEN.
  296.  
  297.               GUBB_ShadowPen (ULONG)
  298.                  Selects which pen to print the shadow text in. Only useful
  299.                  for a bevelbox with a title. Defaults to SHADOWPEN.
  300.                  This tag overrides the GUBB_ShadowColor tag.
  301.  
  302.          PROGRESS_KIND
  303.            Gadget used to display a value out of a total. Can be used to
  304.            display the progress of a search, a diskcopy or anything else.
  305.  
  306.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  307.            a ProgressGad structure.
  308.  
  309.            Extra tags for PROGRESS_KIND:
  310.  
  311.               GUPR_FillColor (ULONG)
  312.                  Selects which color to use to paint the current value of
  313.                  the progress requester with. Defaults to the color of the
  314.                  FILLPEN.
  315.  
  316.               GUPR_FillPen (ULONG)
  317.                  Selects which pen to use to paint the current value of
  318.                  the progress requester with. Defaults to the FILLPEN.
  319.                  This tag overrides the GUPR_FillColor tag.
  320.  
  321.               GUPR_BackColor (ULONG)
  322.                  Selects which color to fill the background of the progress
  323.                  requester with. Defaults to the color of the BACKGROUNDPEN.
  324.  
  325.               GUPR_BackPen (ULONG)
  326.                  Selects which pen to fill the background of the progress
  327.                  requester with. Defaults to the BACKGROUNDPEN.
  328.                  This tag overrides the GUPR_BackColor tag.
  329.  
  330.               GUPR_Current (ULONG)
  331.                  The initial current value of the progress requester. The
  332.                  gadget's current value may be changed later by directly
  333.                  modifying the pg_Current field of the ProgressGad structure.
  334.                  Use GU_UpdateProgress to redraw the progress requester with
  335.                  the new value. The pg_Current field must not be larger than
  336.                  4.294.967.295 / the width of the progress gadget. A "normal"
  337.                  width of 410 pixels allows a current value of 10.737.418.
  338.          Defaults to 0.
  339.  
  340.               GUPR_Total (ULONG)
  341.                  The initial total value of the progress requester. The
  342.                  gadget's total value may be changed later by directly
  343.                  modifying the pg_Total field of the ProgressGad structure.
  344.                  Use GU_UpdateProgress() to redraw the progress requester with
  345.                  the new value. The total value can be as large as a longword
  346.                  allows (4.294.967.295), but you can't display a current value
  347.                  larger than 4.294.967.295 / the width of the progress gadget.
  348.          Defaults to 100.
  349.  
  350.          LABEL_KIND
  351.            A text label. Use this to avoid the use of absolute placement
  352.            of text that you print into the window. Supports the most of
  353.            the text placement and shadow flags for the BEVELBOX_KIND.
  354.  
  355.            The function GU_RefreshBoxes() can be used to redraw all
  356.            text created by LABEL_KIND gadgets.
  357.  
  358.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  359.            a BBoxData structure.
  360.  
  361.            Extra tags for LABEL_KIND:
  362.  
  363.               GULB_TextColor (ULONG)
  364.                  Selects which color to print the text in. Defaults to the
  365.                  color of the TEXTPEN.
  366.  
  367.               GULB_TextPen (ULONG)
  368.                  Selects which pen to print the text in. Defaults to TEXTPEN.
  369.                  This tag overrides the GULB_TextColor tag.
  370.  
  371.               GULB_Flags (ULONG)
  372.                  Flags for text placement, text shadowing and 3D text:
  373.  
  374.                  ___1_____2_____3___
  375.                  |_____|_____|_____| A
  376.                  |_____|_____|_____| B 
  377.                  |_____|_____|_____| C
  378.                  
  379.                  Y-pos flags
  380.                  ~~~~~~~~~~~
  381.                     LB_TEXT_TOP    - Places the topmost point of the text below
  382.                                      the upper border of the box (row A)
  383.  
  384.                     LB_TEXT_MIDDLE - Places the text centered in the box, not
  385.                                      counting in the part of the text that is
  386.                                      below the font's baseline (row B)
  387.  
  388.                     LB_TEXT_BOTTOM - Places the text at the bottom of the box.
  389.                                      Any part of the text that is below the
  390.                                      baseline will be below the box (row C)
  391.  
  392.                  X-pos flags
  393.                  ~~~~~~~~~~~
  394.                     LB_TEXT_CENTER - Places the text centered on the width of
  395.                                      the box (column 2).
  396.  
  397.                     LB_TEXT_LEFT   - Places the text left adjusted in the box
  398.                                      (column 1)
  399.  
  400.                     LB_TEXT_RIGHT  - Places the text right adjusted in the box
  401.                                      (column 3)
  402.  
  403.                  Combined flags
  404.                  ~~~~~~~~~~~~~~
  405.                     LB_TEXT_TOP_CENTER    - LB_TEXT_TOP + LB_TEXT_CENTER
  406.                     LB_TEXT_TOP_LEFT      - LB_TEXT_TOP + LB_TEXT_LEFT
  407.                     LB_TEXT_TOP_RIGHT     - LB_TEXT_TOP + LB_TEXT_RIGHT
  408.  
  409.                     LB_TEXT_MIDDLE_CENTER - LB_TEXT_MIDDLE + LB_TEXT_CENTER
  410.                     LB_TEXT_MIDDLE_LEFT   - LB_TEXT_MIDDLE + LB_TEXT_LEFT
  411.                     LB_TEXT_MIDDLE_RIGHT  - LB_TEXT_MIDDLE + LB_TEXT_RIGHT
  412.  
  413.                     LB_TEXT_BOTTOM_CENTER - LB_TEXT_BOTTOM + LB_TEXT_CENTER
  414.                     LB_TEXT_BOTTOM_LEFT   - LB_TEXT_BOTTOM + LB_TEXT_LEFT
  415.                     LB_TEXT_BOTTOM_RIGHT  - LB_TEXT_BOTTOM + LB_TEXT_RIGHT
  416.  
  417.                  Default is LB_TEXT_TOP|LB_TEXT_CENTER. Combine the x and y
  418.                  position flags by OR:ing them together. Don't combine two X
  419.                  or two Y flags together.
  420.                 
  421.                  Shadow placement flags
  422.                  ~~~~~~~~~~~~~~~~~~~~~~
  423.                     LB_SHADOW_DR - Places the bevel box text shadow one pixel
  424.                                    below and to the right of the text. 
  425.  
  426.                     LB_SHADOW_UR - Places the bevel box text shadow one pixel
  427.                                    above and to the right of the text. 
  428.  
  429.                     LB_SHADOW_DL - Places the bevel box text shadow one pixel
  430.                                    below and to the left of the text. 
  431.  
  432.                     LB_SHADOW_UL - Places the bevel box text shadow one pixel
  433.                                    above and to the left of the text. 
  434.  
  435.                     LB_SUNAT_UL  - Another name for LB_SHADOW_DR
  436.                     LB_SUNAT_DL  - Another name for LB_SHADOW_UR
  437.                     LB_SUNAT_UR  - Another name for LB_SHADOW_DL
  438.                     LB_SUNAT_DR  - Another name for LB_SHADOW_UL
  439.  
  440.                  Default is LB_SHADOW_DR (LB_SUNAT_UL).
  441.  
  442.                     LB_3DTEXT    - This flag can be used in place of the tag
  443.                                    GULB_3DText, TRUE
  444.  
  445.               GULB_3DText (BOOL)
  446.                  Enables the shadow on the text. This tag must be used if
  447.                  GULB_ShadowColor or GULB_ShadowPen isn't used. Another
  448.                  way to enable 3D text is to set the flag LB_3DTEXT in the
  449.                  GULB_Flags tag.
  450.  
  451.               GULB_ShadowColor (ULONG)
  452.                  Selects which color to print the shadow text in. Defaults to
  453.                  the color of the SHADOWPEN.
  454.  
  455.               GULB_ShadowPen (ULONG)
  456.                  Selects which pen to print the shadow text in. Defaults to
  457.                  SHADOWPEN. This tag overrides the GULB_ShadowColor tag.
  458.  
  459.          Changed tags, and additions to GadTools:
  460.  
  461.          LISTVIEW_KIND
  462.  
  463.            GTLV_ShowSelected (UWORD id)
  464.  
  465.               This tag was changed, so that you don't have to create the
  466.               string gadget before all other gadgets. The difference from
  467.               this tag in GadTools, is that we now have to give the ID of
  468.               the string gadget to use to show the selected item.
  469.  
  470.               An example of a valid (and probably most useful) gadget to
  471.               use for GTLV_ShowSelected:
  472.  
  473.               ShowSelGad:
  474.                   dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  475.                   dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  476.                   dc.l    TAG_DONE
  477.  
  478.               This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  479.               array.
  480.  
  481.               Special:
  482.  
  483.               ti_Data = -1    Creates a read-only gadget below the listview,
  484.                               same as for GTLV_ShowSelected, 0  for GadTools.
  485.  
  486.               ti_Data =  x    Gadget ID for the gadget that the selected item
  487.                               should be displayed in. Same as GadTools reaction
  488.                               on a gadget pointer in ti_Data.
  489.  
  490.               This gadget's ti_Data field will be changed during the creation
  491.               of the gadget, but will be changed back before GU_LayoutGadgets
  492.               returns.
  493.  
  494.          MX_KIND
  495.           The gng_GadgetText field in the NewGadget structure can be used
  496.           even with MX_KIND gadgets. This should have been included in
  497.           GadTools. The gadget text will always be placed ABOVE the gadget,
  498.           on the same side as the other texts for the gadget. Positions are
  499.           checked against WBPattern & SerialPrefs to get them "right". The
  500.           GU_GadgetText and GU_LocaleText tags are used to access this field.
  501.  
  502.  
  503.    Tags for all gadget kinds:
  504.  
  505.    Gadget width control:
  506.  
  507.       GU_Width (UWORD wid)
  508.          Absolute width of the gadget. Not recommended to use for other
  509.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  510.  
  511.       GU_DupeWidth (UWORD id)
  512.          Duplicate the width of another gadget.
  513.  
  514.       GU_AutoWidth (WORD add)
  515.          Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  516.      the gadget width will be calculated by checking the length of
  517.      all alternatives and using the one that is widest + 26 as width.
  518.  
  519.       GU_Columns (UWORD numcols)
  520.          Set the gadget width so that approximately ti_Data columns of
  521.          text will fit.
  522.  
  523.       GU_AddWidth (WORD add)
  524.          Add ti_Data to the total width calculation.
  525.  
  526.       GU_MinWidth (UWORD wid)
  527.          Make the gadget at least ti_Data pixels wide.
  528.  
  529.       GU_MaxWidth (UWORD wid)
  530.          Make the gadget at most ti_Data pixels wide.
  531.  
  532.       GU_AddWidChar (WORD chars)
  533.          Add the length of ti_Data characters to the total width calculation.
  534.  
  535.       GU_FractWidth (LONG parts)
  536.      Divide or multiply the gadget's width with ti_Data. A positive
  537.      value divides the gadget's width by the ti_Data, a negative ti_Data
  538.      multiplies the gadget's width with ti_Data.
  539.  
  540.     Gadget height control:
  541.  
  542.       GU_Height (UWORD hei)
  543.          Absolute height of the gadget. Not recommended to use for other
  544.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  545.         
  546.       GU_DupeHeight (UWORD id)
  547.          Duplicate the height of another gadget.
  548.  
  549.       GU_AutoHeight (WORD add)
  550.          Height = height of the gadget's font + ti_Data. This tag doesn't
  551.          work as it should with MX_KIND gadgets. Will be fixed later.
  552.          Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  553.  
  554.       GU_HeightFactor (UWORD numlines)
  555.          Set the gadget height to approximately ti_Data lines.
  556.  
  557.       GU_AddHeight (WORD add)
  558.          Add ti_Data to the total height calculation.
  559.  
  560.       GU_MinHeight (UWORD wid)
  561.          Make the gadget at least ti_Data pixels high.
  562.  
  563.       GU_MaxHeight (UWORD wid)
  564.          Make the gadget at most ti_Data pixels high.
  565.  
  566.       GU_AddHeiLines (WORD numlines)
  567.          Add the height of ti_Data/2 lines to the final height calculation.
  568.          The numlines argument is given in units of 1/2 lines to get
  569.          better resolution (ti_Data of 4 means that the height of 2
  570.          lines should be added).
  571.  
  572.       GU_FractHeight (LONG parts)
  573.      Divide or multiply the gadget's height with ti_Data. A positive
  574.      value divides the gadget's height by the ti_Data, a negative ti_Data
  575.      multiplies the gadget's height with ti_Data.
  576.  
  577.    Gadget top edge control:
  578.  
  579.       GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  580.       allows any bottom edge control tag to adjust the height, so that both
  581.       top and bottom edges will be correct.
  582.  
  583.       GU_Top (UWORD ypos)
  584.          Absolute top edge of the gadget. Not recommended to use for other
  585.          gadgets than the top-most gadgets.
  586.  
  587.       GU_TopRel (UWORD id)
  588.          Make the top edge relative to another gadgets bottom edge. This
  589.          gadget will be placed BELOW the given gadget.
  590.  
  591.       GU_AddTop (WORD add)
  592.          Add ti_Data to the final top edge calculation.
  593.  
  594.       GU_AlignTop (UWORD id)
  595.          Align the top edge of the gadget with another gadgets top edge.
  596.  
  597.       GU_AdjustTop (WORD add)
  598.          Add the height of the text font + ti_Data to the top edge.
  599.  
  600.       GU_AddTopLines (WORD numlines)
  601.          Add the height of ti_Data/2 lines to the final top edge. The
  602.          numlines argument is given in units of 1/2 lines to get better
  603.          resolution (ti_Data of 4 means that the height of 2 lines
  604.          should be added).
  605.  
  606.    Gadget bottom edge control:
  607.  
  608.       GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  609.       gadget, and allows any top edge control tag to adjust the height, so that
  610.       both top and bottom edges will be correct.
  611.  
  612.       GU_Bottom (UWORD ypos)
  613.          Absolute bottom edge of the gadget. Not recommended to use for other
  614.          gadgets than the bottom-most gadgets. Should not be necessary to use
  615.          at all.
  616.  
  617.       GU_BottomRel (UWORD id)
  618.          Make the bottom edge relative to another gadgets top edge. This
  619.          gadget will be placed ABOVE the given gadget.
  620.  
  621.       GU_AddBottom (WORD add)
  622.          Add ti_Data to the final bottom edge calculation.
  623.  
  624.       GU_AlignBottom (UWORD id)
  625.          Align the bottom edge of the gadget with another gadgets bottom edge.
  626.  
  627.       GU_AdjustBottom (WORD add)
  628.          Subtract the height of the gadget's font + ti_Data from the top edge.
  629.          This will move the gadget UPWARDS (ti_Data + font height) pixels.
  630.  
  631.    Gadget left edge control:
  632.  
  633.       GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  634.       and allows any right edge control tag to adjust the width, so that both
  635.       left and right edges will be correct.
  636.  
  637.       GU_Left (UWORD xpos)
  638.          Absoulute left edge of the gadget. Not recommended to use for other
  639.          gadgets than the left-most gadgets.
  640.  
  641.       GU_LeftRel (UWORD id)
  642.          Make the left edge relative to another gadgets right edge. This
  643.          gadget will be placed TO THE RIGHT of the given gadget.
  644.  
  645.       GU_AddLeft (WORD add)
  646.          Add ti_Data to the final left edge calculation.
  647.  
  648.       GU_AlignLeft (UWORD id)
  649.          Align the left edge of the gadget with another gadgets left edge.
  650.  
  651.       GU_AdjustLeft (WORD add)
  652.          Add the width of the gadget label + ti_Data to the left edge.
  653.  
  654.       GU_AddLeftChar (WORD chars)
  655.          Add the length of ti_Data characters to the left edge.
  656.  
  657.    Gadget right edge control:
  658.  
  659.       GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  660.       gadget, and allows any left edge control tag to adjust the width, so
  661.       that both left and right edges will be correct.
  662.  
  663.       GU_Right (UWORD xpos)
  664.          Absoulute right edge of the gadget. Not recommended to use for other
  665.          gadgets than the right-most gadgets. Should not be necessary to use
  666.          at all.
  667.  
  668.       GU_RightRel (UWORD id)
  669.          Make the right edge relative to another gadgets left edge. This
  670.          gadget will be placed TO THE LEFT of the given gadget.
  671.  
  672.       GU_AddRight (WORD add)
  673.          Add ti_Data to the final right edge calculation.
  674.  
  675.       GU_AlignRight (UWORD id)
  676.          Align the right edge of the gadget with another gadgets right edge.
  677.  
  678.       GU_AdjustRight (WORD add)
  679.          Add the width of the gadget label + ti_Data to the left edge.
  680.  
  681.     Other tags:
  682.  
  683.       GU_ToggleSelect (BOOL)
  684.          Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  685.          gadgets.
  686.  
  687.       GU_Selected (BOOL)
  688.          Set the initial value of a toggle select gadget.
  689.  
  690.       GU_Hotkey (CHAR)
  691.          Hotkey that should simulate a press (release) of a gadget.
  692.  
  693.       GU_HotkeyCase (BOOL)
  694.          Make the hotkey case-sensitive. Default is not case sensitive.
  695.  
  696.       GU_LabelHotkey (BOOL)
  697.          Get the hotkey directly from the gadget's label. The hotkey can
  698.          be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  699.  
  700.       GU_RawKey (BYTE)
  701.          Use a rawkey as a gadget hotkey. May not be case-sensitive.
  702.         
  703.       GU_HelpGadget (ULONG)
  704.          GadgetID of the TEXT_KIND or the STRING_KIND to show the gadget's
  705.          help text in.
  706.  
  707.       GU_HelpText (UBYTE *)
  708.          The text that is shown in the help gadget (GU_HelpGadget) when the
  709.          mouse pointer is placed on the gadget.
  710.  
  711.       GU_LocaleHelp (ULONG stringid)
  712.          Get gadget help text from a catalog. This makes it easy to create
  713.          localized help strings in the program.
  714.    Tags that gives access to other fields in the NewGadget structure:
  715.  
  716.       GU_GadgetText (UBYTE *)
  717.          A pointer to the gadget's label. Will be copied directly into the
  718.          gng_GadgetText field of the NewGadget structure.
  719.  
  720.       GU_TextAttr (struct TextAttr *)
  721.          A pointer to an initialized TextAttr structure (to select the font).
  722.          Will be copied directly into the gng_TextAttr field of the NewGadget
  723.          structure.
  724.  
  725.       GU_Flags (ULONG)
  726.          Gadget flags. Currently available flags are as for GadTools, but
  727.          here is a short list of them:
  728.  
  729.          PLACETEXT_LEFT - Place the gadget label right aligned on the left
  730.                           side of the gadget.
  731.  
  732.          PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  733.                            side of the gadget.
  734.  
  735.          PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  736.  
  737.          PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  738.  
  739.          PLACETEXT_IN - Place the gadget label centered inside the gadget.
  740.  
  741.          NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  742.  
  743.       *** GU_UserData (APTR) *** REMOVED in v37.7 ***
  744.  
  745.       GU_LocaleText (ULONG stringid)
  746.          Get gadget label from a catalog. This allows easy localization of
  747.          all new programs.
  748.  
  749.  
  750.    RESULT
  751.     gad_info - a pointer to a private structure. You must keep this
  752.            value and pass it to GU_FreeLayoutGadgets() later on
  753.            in order to free up all resources used by your gadgets.
  754.            This pointer is also used in a lot of other functions
  755.            in this library.
  756.  
  757.    NOTES
  758.     You must be careful with the taglist in the lg_LayoutTags field.
  759.     Tags are processed sequentally in the order you give them in, and
  760.     if a tag references another gadget (eg. the GL_TopRel tag), then
  761.     processing of the current gadget halts while the referenced gadget
  762.     is processed (if it has not already been processed). Problems can
  763.     occur if this gadget refers back to the original gadget that
  764.     referenced if, if it is referring to a field that has not yet been
  765.     processed in that gadget.
  766.  
  767.         Also note that you do not have to specify any tags that do not
  768.         change from gadget to gadget. Just be sure that you know in which
  769.     order the gadgets are processed (eg. relatives etc).
  770.  
  771.     Another thing to note, is that we have tried to make the processing
  772.     of position and width / height tags as usable as possible, what I
  773.     mean with this, is that if you eg first define the left edge and
  774.     then define the right edge, the width will change. BUT, there are
  775.     special cases when this isn't true. This is because we have tried
  776.     out this and decided that this was the best way to do it.
  777.  
  778.     Here comes some examples of the special cases;
  779.  
  780.     dc.l    GU_AlignLeft, GAD_1    ; Left edge aligned with GAD_1's left.
  781.     dc.l    GU_AlignRight, GAD_2    ; This stretches the gadget, so that
  782.                     ; both the left and right edges are
  783.                     ; positioned as defined.
  784.     ; Then, if we want to move the right edge 2 pixels right, and the left
  785.     ; edge two pixels right, we might try this:
  786.  
  787.     dc.l    GU_AddLeft, -2        ; This works as we want, it moves the
  788.                     ; left edge to the right place, but it
  789.                     ; also moves the whole gadget two
  790.                     ; pixels left..
  791.  
  792.     dc.l    GU_AddRight, 2        ; <- This is a common mistake. This
  793.                     ; moves the whole gadget to the right.
  794.                     ; Ie. it is moved back to the old
  795.                     ; position, not as we wanted...
  796.  
  797.     ; But if we replace the previous line with the following;
  798.  
  799.     dc.l    GU_AddWith,4        ; This works just as we wanted it to.
  800.                     ; Now the gadget should be 4 pixels
  801.                     ; wider, two to the left and two to
  802.                     ; the right.
  803.  
  804.     The same goes for GU_AddHeight and GU_AddBottom etc.
  805.  
  806.     This is actually a feature. Sometimes you might want to move the whole
  807.     button, so we made it work this way.
  808.  
  809.  
  810.    SEE ALSO
  811.     GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
  812.     GU_RefreshWindow(), GU_RefreshBoxes(), GU_UpdateProgress()
  813.